Inside Macintosh: QuickDraw GX Objects /

Chapter 8 - Tag Objects / Tag Objects Reference

Functions / Creating and Manipulating Tag Objects

GXNewTag

You can use the GXNewTag function to create a new tag object.

gxTag GXNewTag(long tagType, long length, const void *data);

tagType

A 4-byte identifier specifying the type of tag object to be created.

length

The length in bytes of the data to place in the tag object.

data

A pointer to the data to place in the tag object.

function result

A reference to the newly created tag object.

DESCRIPTION

The GXNewTag function creates a tag object, with an owner count of 1, containing whatever data you supply. The tag type is an application-defined, 4-byte tag (commonly expressed on the Macintosh with four characters, such as 'Cary') that you supply to specify the type of data contained in the tag object. You cannot supply a value of 0.

You can specify a value of zero for the length parameter, in which case GXNewTag creates the tag object but places no data into it. (In that case, the data pointer must be nil, or else GXNewTag posts an inconsistent_parameters error.)

SPECIAL CONSIDERATIONS

You cannot specify a tag type of zero. Apple Computer, Inc., reserves all tag types that can be expressed as four lowercase characters (such as 'atag').

Tag types expressed as four characters may not be portable to systems other than the Macintosh; tag types defined numerically are portable.

If no error occurs, the GXNewTag function creates a tag object; you are responsible for disposing of that object when you no longer need it.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
type_is_nil
inconsistent_parameters

SEE ALSO

Currently defined tag types for tag objects are listed in Table 8-1 on page 8-6.